https://retellai.com/?utm_source=discord&utm_medium=seo logo
Powered by
im setting call campaigns in my app but im not sur...
# ❓・ai-evy-support
c
@AI Evy im setting call campaigns in my app but im not sure how to send you the phone numbers and also some set up like ai agent, leads, contacts infos and variables and etc, can you give me the complete information i need to send to retell so we can send call campaigns from our app to retell? also retell need to send us back like pick up/no pick up/appointment booked and other varaibles so we can use as metrics. one important details we already have inbound and outbound ai calls set and its working 100%, im just looking to get this campaign set up, so i think its better you understand how our current set up is so we can reuse some of the set up we already have?
a
Thanks for tagging me @Client Nexus. I'll look through relevant sources and get back to you shortly.
### Answer --- Since you already have inbound/outbound calls working, you can reuse your existing agent and phone number setup for campaigns. Here's what you need to send to Retell for each call: ## Required Parameters for Outbound Calls | Parameter | Type | Description | |-----------|------|-------------| | 
from_number
| string (E.164) | Your Retell-managed or imported number | | 
to_number
| string (E.164) | Destination number | | 
override_agent_id
| string | Override the agent used for this call (optional) | | 
metadata
| object | Free-form metadata stored with the call | | 
retell_llm_dynamic_variables
| object | Key–value strings injected into prompts/tools | [(1) ]() ## API Example for Campaign Calls
Copy code
javascript
const registerCallResponse = await retell.call.createPhoneCall({
 from_number: '+14157774444', // replace with the number you purchased
 to_number: '+12137774445', // replace with the number you want to call
 // Optional: per-call agent selection and overrides
 override_agent_id: 'agent_abc123',
 override_agent_version: 0, // or omit to use latest
 agent_override: {
 agent: {
 voice_speed: 1.1,
 enable_backchannel: true,
 },

 // retell_llm or conversation_flow overrides are also supported
 },
 retell_llm_dynamic_variables: { // dynamic variables (optional, string values only)
 name: 'John Doe',
 blood_group: 'B+'
 }, 
 custom_sip_headers: { // replace with custom sip headers you want to send (optional)
 X-Custom-Header: 'Custom Value'
 }
}) ;
## Getting Metrics Back (Pick Up, Appointment Booked, etc.) *Option 1: Webhooks (Real-time) * Set up webhooks to receive instant notifications for: - Call Started – When the call connects - Call Ended – Final status and duration - Call Analyzed – Transcript and analysis ready - Call Failed – Error details and reasons Option 2: API Polling Use the Get Call API to retrieve full transcript, recording, latency metrics, function call logs, call duration, and status. ## Capturing Custom Variables (e.g., "appointment_booked") Use the Extract Dynamic Variables tool to capture values during the call (like appointment confirmation, interest level, etc.) : [(2) ]() 1. Add an Extract Dynamic Variable Tool to your agent 2. Define variables with types: 
Text
, 
Number
, 
Enum
, or 
Boolean
3. Update your prompt to specify when to extract, e.g.:
Copy code
When user states his name and phone number, please extract the information by calling the `extract_user_details` function.
## For Batch/Campaign Calling For high-volume campaigns, check out the [Batch Calling Guide](/deploy/make-batch-call) referenced in the docs for uploading contact lists and scheduling. [(1) ]() ---
​ To learn more, see the sources I considered: [[1] Outbound Calls (Make Calls)](https://docs.retellai.com/deploy/outbound-call) [[2] Extract Dynamic Variables](https://docs.retellai.com/build/single-multi-prompt/extract-dv) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy what is better to run a campaign of calls in my app using retell? batch calls or making individual API calls in a loop?
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer --- Batch Calling is the recommended approach for campaigns. Here's why: ## Advantages of Batch Calling - Handles concurrency automatically – Batch Calling queues your calls without hitting concurrency limits, ensuring a seamless experience. [(1) ]() - Cost efficient – Pricing is $0.005 per dial (20k calls for $100) . - Scheduling options – You can "Send Now" to dispatch all calls immediately or use "Scheduled Time" to send out calls at a scheduled time. - Supports dynamic variables – For dynamic variables, add additional columns in the CSV with custom data for each recipient (e.g., a column header 
first_name
can be referenced as 
{{first_name}}
) . [(2) ]() ## API Example
Copy code
javascript
import Retell from 'retell-sdk';
const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
}) ;
const batchCallResponse = await client.batchCall.createBatchCall({
  from_number: '+14157774444',
  tasks: [{ to_number: '+12137774445' }],
}) ;
console.log(batchCallResponse.batch_call_id) ;
[(3) ]() ## When to Use Individual API Calls Individual calls via the Create Phone Call API are better suited for: - Single, on-demand outbound calls - Real-time triggered calls (e.g., user action triggers a callback) For high-volume campaign use cases, Batch Calling handles the queuing and rate limiting for you, so you don't have to manage concurrency in your own loop.
​ To learn more, see the sources I considered: [[1] Batch Calling, New Docs, and More Improvements!](https://www.retellai.com/changelog/batch-calling-new-docs-and-more-improvements) [[2] Create Batch calls](https://docs.retellai.com/deploy/make-batch-call) [[3] Create Batch Call](https://docs.retellai.com/api-references/create-batch-call) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy can you provide me the full set up technical so i can send to my team? we already have the front end so we just need to set the backend now, if you have qustion to understand out structure to provide a better approach send me and i will get with them
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer --- Here's the full backend technical setup for running call campaigns with Retell AI: ## 1. Install the SDK
Copy code
javascript
npm i retell-sdk
[(1) ]() ## 2. Initialize the Client
Copy code
javascript
import Retell from 'retell-sdk';
const retellClient = new Retell({
  apiKey: "YOUR_API_KEY",
}) ;
## 3. Phone Number Setup Your 
from_number
must be a phone number you've purchased and configured through Retell AI. [(2) ]() To create/configure a phone number:
Copy code
javascript
import Retell from 'retell-sdk';
const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
}) ;
const phoneNumberResponse = await client.phoneNumber.create() ;
console.log(phoneNumberResponse.inbound_agent_id) ;
To update an existing number with an outbound agent:
Copy code
javascript
const phoneNumberResponse = await client.phoneNumber.update('+14157774444', {
  inbound_agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
  nickname: 'Frontdesk Number',
  outbound_agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
}) ;
[(3) ]() ## 4. Create Batch Calls (Recommended for Campaigns)
Copy code
javascript
import Retell from 'retell-sdk';
const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
}) ;
const phoneCallResponse = await client.call.createPhoneCall({
  from_number: '+14157774444',
  to_number: '+12137774445',
}) ;
console.log(phoneCallResponse.agent_id) ;
For dynamic variables and agent overrides, use this payload structure:
Copy code
json
{
  "from_number": "+16504144521",
  "to_number": "your_target_number",
  "override_agent_id": "agent_71724df7636716ceb3a7e244c8",
  "retell_llm_dynamic_variables": {
    "name": "Sarah"
  }
}
[(2) ]() ## 5. Set Up Webhooks to Receive Metrics Configure webhooks to receive real-time call updates. [(4) ]() | Event Type | Description | Payload | |------------|-------------|---------| | 
call_started
| Triggered when a new call begins | Basic call information | | 
call_ended
| Triggered when a call completes, transfers, or encounters an error | All fields from the call object except 
call_analysis
| | 
call_analyzed
| Triggered when call analysis is complete | Full call data including 
call_analysis
object | Sample webhook payload:
Copy code
json
{
  "event": "call_ended",
  "call": {
    "call_type": "phone_call",
    "from_number": "+12137771234",
    "to_number": "+12137771235",
    "direction": "inbound",
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "call_status": "registered",
    "metadata": {},
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "start_timestamp": 1714608475945,
    "end_timestamp": 1714608491736,
    "disconnection_reason": "user_hangup",
    "transcript": "...",
    "transcript_object": [ [Object], [Object], [Object], [Object] ],
    "transcript_with_tool_calls": [ [Object], [Object], [Object], [Object] ],
    "opt_out_sensitive_data_storage": false
  }
}
The webhook has a timeout of 10 seconds. If no success status (2xx) is received, the webhook will be retried up to 3 times. ## Key Points to Verify 1. Your 
from_number
must be purchased and configured through Retell AI [(2) ]() 2. The phone number should have an 
outbound_agent_id
configured, or use 
override_agent_id
in your request 3. Use 
retell_llm_dynamic_variables
(not 
custom_data
) for passing variables For more detailed SDK examples, check out: - [Node.js SDK Examples]() [(1) ]() - [Python SDK Examples]() ---
​ To learn more, see the sources I considered: [[1] SDKs](https://docs.retellai.com/get-started/sdk) [[2] 404 Error on Create a Phone Call](https://retell.discourse.group/t/404-error-on-create-a-phone-call/22) [[3] Here is how that can be fixed](https://retell.discourse.group/t/here-is-how-that-can-be-fixed/23) [[4] Webhook Overview](https://docs.retellai.com/features/webhook-overview) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy if i set a campaign with more than 20 leads will retell automatically call the others leads? because we have the 20 concurrent calls, or do i need to set something up in my app to run smthly?
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
​ To learn more, see the sources I considered: [[1] Batch Calling, New Docs, and More Improvements!](https://www.retellai.com/changelog/batch-calling-new-docs-and-more-improvements) [[2] Create Batch calls](https://docs.retellai.com/deploy/make-batch-call) ​
### Answer Yes, Retell handles this automatically when using Batch Calling. [(1) ]() Batch Calling queues your calls without hitting concurrency limits, ensuring a seamless experience. This means: - You don't need to build queue management in your app - Calls are initiated as concurrency slots become available [(2) ]() - Your batch can contain more leads than your concurrency limit—Retell will process them in order as slots free up Your batch call status will show as "Ongoing" while currently in progress, with calls initiated as concurrency slots become available. So if you submit 100 leads with a 20 concurrent call limit, Retell will automatically dial the next lead when a slot opens up. No additional setup required on your end.
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy can you advise if our set up is correct? Our current setup (end-to-end) — “Batch Calls” 1) Frontend When you “Launch campaign”, the app calls the Edge Function: execute-campaign with campaignId. 2) Edge Function: execute-campaign A) Retrieves leads Campaign_leads table (status = pending) Fallback: campaign.config.selectedLeadIds if campaign_leads is empty (and upserts into campaign_leads) B) Retrieves contacts Contacts table with .in('id', contactIds) C) CALL Mode → Batch If voicemailOnly is enabled → NOT batch (remains in “individual drop-voicemail”) Otherwise → Batch call Retell Selected agent: campaign.config.steps[].agentId (step type call) or campaign.config.selectedAgentId Fallback: first agent of the subaccount with retell_agent_id not null Outgoing number: getDefaultPhoneWithSync(...) → defaultPhone.phone_number (E.164) Numbers leads: normalizePhoneToE164(contact.phone) (skip + mark failed if invalid) D) Payload sent to Retell (Batch Call API) Endpoint: POST https://api.retellai.com/v2/create-batch-call Body: { "from_number": "+1XXXXXXXXXX", "override_agent_id": "retell_agent_id_here", "name": "Campaign: ()", "tasks": [ { "to_number": "+1YYYYYYYYYY", "retell_llm_dynamic_variables": { "__subaccount_id__": "...", "__agent_id__": "...", "__contact_id__": "...", "first_name": "...", "last_name": "...", "email": "...", "phone": "...", "business_name": "...", "website": "...", "company_information": "...", "service_list": "...", "knowledge_base": "...", "...contact.custom_fields": "..." }, "metadata": { "campaign_id": "...", "campaign_name": "...", "contact_id": "...", "subaccount_id": "...", "source": "batch_campaign" } } ] } E) Tracking / statuses
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer Your setup looks solid overall. Here are a few observations based on the documented API: ## API Endpoint The documented endpoint is:
Copy code
POST /create-batch-call
[(1) ]() Your payload references `/v2/create-batch-call`—verify this matches the current API base URL in the SDK or docs. ## Required Parameters Your payload includes the required fields: - 
from_number
(E.164 format) ✓ - 
tasks
array with 
to_number
✓ ## Supported Task Fields Based on the API reference, each task object supports: - 
to_number
✓ Your use of 
retell_llm_dynamic_variables
and 
metadata
within tasks aligns with how dynamic variables work for personalization. [(2) ]() ## Optional Parameters You May Want to Consider The API also supports: [(1) ]() - 
name
– for your own reference ✓ (you have this) - 
trigger_timestamp
– to schedule calls for a future time - 
reserved_concurrency
– reserve a portion of your org concurrency for batch processing - 
call_time_window
– define allowed calling windows in a specific timezone ## One Limitation to Note A Discord user asked about overriding the default agent ID per phone number within a batch request, which suggests 
override_agent_id
at the batch level (as you're doing) is the standard approach—there's no documented way to assign different agents per task within the same batch. [(3) ]() ## Tracking Batch Status Once created, batch calls are classified by status: Draft, Planned, Ongoing, or Sent. [(2) ]() Metrics available include: Sent, Picked Up, and Successful calls.
​ To learn more, see the sources I considered: [[1] Create Batch Call](https://docs.retellai.com/api-references/create-batch-call) [[2] Create Batch calls](https://docs.retellai.com/deploy/make-batch-call) [[3] Discord message from @zeeshanayub on 2025-08-01](https://discord.com/channels/1186424376300679209/1294891368505937952/1400701674485452871) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy look like we are having an error regarding the phone number need to be set to do outbound as well? or we have an wrong set up? since we have multiple users this should be atuomatically set how can we do? my team have sent me this In Retell dashboard → Phone Numbers → +14159425808, set/configure an Outbound Agent ID for that phone number (Retell appears to require this even when override_agent_id is provided).
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer Based on the API documentation, the 
outbound_agent_id
field on the phone number determines which agent is used for outbound calls when no override is provided. [(1) ]() If 
outbound_agent_id
is 
null
, the number would not be able to initiate outbound calls without an agent id override. ## Programmatic Solution for Multiple Users Since you have multiple users, you can automate the phone number configuration via the Update Phone Number API:
Copy code
javascript
import Retell from 'retell-sdk';
const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
}) ;
const phoneNumberResponse = await client.phoneNumber.update('+14157774444', {
  inbound_agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
  nickname: 'Frontdesk Number',
  outbound_agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
}) ;
console.log(phoneNumberResponse.inbound_agent_id) ;
## Suggested Workflow 1. When a new phone number is created or imported for a user, immediately call the Update Phone Number API to set the 
outbound_agent_id
2. You can also set this during phone number creation by passing 
outbound_agent_id
in the Create Phone Number request [(2) ]() This way, each user's phone number is automatically configured for outbound calls without manual dashboard intervention.
​ To learn more, see the sources I considered: [[1] Update Phone Number](https://docs.retellai.com/api-references/update-phone-number) [[2] Create Phone Number](https://docs.retellai.com/api-references/create-phone-number) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy can you advise regarding the variables you have for batch capaigns so i can set an ui/ux in my app so my users can see results and we can set auatomtions triggers using this, including also if no pick up add tag in our app or identify so we can continue like next day setting another call automatically in multi step campaigns like "“wait 1 day then do step 2"
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer --- ## Webhook Events for Campaign Tracking Use webhooks to receive real-time call data for your UI/UX and automation triggers: [(1) ]() | Event Type | Description | Payload | |------------|-------------|---------| | 
call_started
| Triggered when a new call begins | Basic call information | | 
call_ended
| Triggered when a call completes, transfers, or encounters an error | All fields from the call object except 
call_analysis
| | 
call_analyzed
| Triggered when call analysis is complete | Full call data including 
call_analysis
object | ## Key Variables for Identifying "No Pick Up" and Other Outcomes From the 
call_ended
webhook payload, use 
disconnection_reason
to identify call outcomes: [(2) ]() Relevant values include: - 
dial_busy
– Line was busy - 
dial_failed
– Dial failed - 
dial_no_answer
– No answer - 
user_hangup
– User hung up - 
agent_hangup
– Agent ended call - 
voicemail_reached
– Went to voicemail ## Sample Webhook Payload Structure
Copy code
json
{
  "event": "call_ended",
  "call": {
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "call_status": "registered",
    "metadata": {},
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "start_timestamp": 1714608475945,
    "end_timestamp": 1714608491736,
    "disconnection_reason": "user_hangup",
    "transcript": "..."
  }
}
[(1) ]() ## Additional Variables from Get Call API For detailed metrics, use the Get Call API which returns: [(2) ]() - 
call_status
– 
registered
, 
ongoing
, 
ended
, 
error
- 
duration_ms
– Call duration in milliseconds - 
transcript
/ 
transcript_object
– Full conversation - 
call_analysis
– Includes 
call_summary
, 
user_sentiment
, 
call_successful
, 
in_voicemail
, and 
custom_analysis_data
## Batch Call Metrics From the dashboard, batch calls show: [(3) ]() , [(4) ]() - Sent – Total calls dispatched - Picked Up – Calls answered - Successful – Completed successfully [(3) ]() ## Automation Workflow Suggestion For multi-step campaigns ("wait 1 day then step 2") : 1. Receive 
call_ended
webhook 2. Check 
disconnection_reason
(e.g., 
dial_no_answer
, 
dial_busy
) 3. Tag the contact in your app and schedule the next batch call using 
trigger_timestamp
(Unix timestamp in milliseconds) [(5) ]()
Copy code
javascript
const batchCallResponse = await client.batchCall.createBatchCall({
  from_number: '+14157774444',
  tasks: [{ to_number: '+12137774445' }],
  trigger_timestamp: 1735718400000
}) ;
​ To learn more, see the sources I considered: [[1] Webhook Overview](https://docs.retellai.com/features/webhook-overview) [[2] Get Call](https://docs.retellai.com/api-references/get-call) [[3] Create Batch calls](https://docs.retellai.com/deploy/make-batch-call) [[4] Scale Outreach with Efficient Batch Calling | Retell AI](https://www.retellai.com/features/batch-call) [[5] Create Batch Call](https://docs.retellai.com/api-references/create-batch-call) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
PreviousNext
Powered by